<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" id="text">
<head>
  <title>Text Views</title>
</head>

<body>

<h1>Text Views </h1>

<p> This section describes the <classname>LzText</classname> and
<classname>LzInputText</classname> classes and the <tagname link="true">richinputtext</tagname> component. It assumes you're familiar
with basic LZX concepts such views (<xref linkend="views"/>), methods, and attributes.</p>
<p>For a gentle introduction, see the <a href="${tutorials}text.html">Text and Font</a> tutorial.</p>
<h2>Summary of properties</h2>
<p>
Unless an explicit width and height are specified as attributes, the
text field will by default be sized to a width and height which
encloses its compile-time text content.  The text field can
be set to automatically resize itself when its value is modified at
runtime, by setting the attribute <code>resize="true"</code> . 
</p> 


<code>
&lt;text resize="true" bgcolor="#ffcccc" name="t1"&gt;Initial text from server.&lt;/text&gt; 
</code>

<p>
Text can be set to automatically wrap at the right margin, by setting the 
attribute <code>multiline="true"</code>.
</p>
<h3>HTML formatting</h3>
<p>Within a text element, a simple subset of HTML formatting is
supported for the text content, supporting XHTML tags
<tagname>br</tagname>, <tagname>b</tagname>, <tagname>i</tagname>,
<tagname>u</tagname>, <tagname>font</tagname>, <tagname>pre</tagname>,
and <tagname>a</tagname>.</p>

<p>Examples below show examples of using XHTML tags in text content:</p>

<p>For font style, the text element itself supports attributes for
setting the font parameters. These are the
<attribute>font</attribute>, <attribute>fontstyle</attribute>, and
<attribute>fontsize</attribute> attributes:</p>

<example title="setting font, fonstyle and fontsize">
&lt;canvas height="50" layout="y"&gt;
  &lt;text fontstyle="bold"&gt;Default bold&lt;/text&gt;
  &lt;text fontstyle="italic"&gt;Default italic&lt;/text&gt;
  &lt;text fontstyle="bold italic"&gt;Default bold italic&lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>Within the text content, HTML tags may also be used:</p>

<example title="HTML tags within text">
&lt;canvas height="50" layout="y"&gt;
  &lt;text&gt;&lt;b&gt;Default bold&lt;/b&gt;&lt;/text&gt;
  &lt;text&gt;&lt;i&gt;Default italic&lt;/i&gt;&lt;/text&gt;
  &lt;text fontstyle="bold"&gt;&lt;i&gt;Default bold italic&lt;/i&gt;&lt;/text&gt;
&lt;/canvas&gt;    
</example>

<p>Text can contain preformatted regions, where linebreaks and whitespace
are preserved:</p>

<example title="Preformatted text">
&lt;canvas height="80"&gt;
  &lt;text id="ttext" multiline="true" height="300"&gt;
    This text field contains some preformatted text
    &lt;pre&gt;
    This is a line of text.

    here was a blank line before this line.
    And another line of text.
    &lt;/pre&gt;
   &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>Within a text element, the HTML <i>font</i> tag supports the
<attribute>face</attribute>, <attribute>size</attribute>, and
<attribute>color</attribute> attributes. The color must be specified
as an RGB hex string of the form "<code>#<var>RRGGBB</var></code>".</p>

<example title="Setting text colors using RGB strings">
&lt;canvas height="60" layout="y"&gt;
  &lt;font name="Times Roman" src="bitstream-vera-1.10/vera.ttf"/&gt;
  
  &lt;text height="30"&gt;
    &lt;font face="Times Roman" size="24"&gt;Times Roman&lt;/font&gt;
  &lt;/text&gt;
  &lt;text bgcolor="#ffcccc"&gt;
    &lt;font color="#FF0000"&gt;C&lt;/font&gt;&lt;font color="#FFFF00"&gt;O&lt;/font&gt;&lt;font color="#00FFCC"&gt;L&lt;/font
    &gt;&lt;font color="#CC00CC"&gt;O&lt;/font&gt;&lt;font color="#AABB00"&gt;R&lt;/font&gt;&lt;font color="#DDA00A"&gt;S&lt;/font&gt;
  &lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>If you wish to include HTML escape characters in the text value,
you can use entity codes such as <code>&amp;amp;</code> or
<code>&amp;lt;</code> (or the numeric codes
<code>&amp;#<var>ddd</var>;</code>), or you may enclose the characters
using a CDATA region:</p>

<example title="Escaping HTML characters">
&lt;canvas height="20"&gt;
  &lt;text bgcolor="#ffcccc"&gt;&lt;![CDATA[&lt;b&gt;this text shouldn't be bold&lt;/b&gt;]]&gt;&lt;/text&gt; 
&lt;/canvas&gt;
</example>

<h4>Text Scrolling</h4>

<p>Text fields can be scrolled using the <method>setXScroll</method>
and <method>setYScroll</method> methods. The arguments to these
functions set the pixel position of the top line of text relative to
the text view bounding box, and should be less than or equal to
zero. When the text is scrolled horizontaly or vertically, an
<event>onscrollx</event> or <event>onscrolly</event> event will be sent.</p>

<h3>Text Width</h3>

<p>
     A text view which is not given an explicit width will default to
     have a width which is the length of the longest line. (See below, however, about
resizing text fields.)Given that
     the initial text content is normalized according to HTML
     normalization rules, and if you do not specify an explicit width,
     the only way a linebreak will occur is if you have an explicit
     HTML linebreak code such as <code>&lt;br/&gt;</code>,
     <code>&lt;p/&gt;</code> or a newline inside of the text contents
     of a <tagname>pre</tagname> element.
        </p>
<p>
     The text view will default to a height which encloses all of
     the lines of text.
        </p>


<!--note> This only applied to flash5. In flash6 text, you can ask the text for its textheight.
Laszlo will have a method for that in a future release. </note-->
<p>
     If you want to know the total height of the text in a text field
     (if you want to know how large to draw a scrollbar, for example)
     there are a couple of ways to figure this out: For a
     <code>multiline=false</code> text field (i.e., one in which
     wrapping is not being done automatically by the system), you must
     manually count the number of linebreaks in the text, and then
     multiply by the font height.
       </p>

<!--note> again, this is not needed in flash6, just use the textheight method</note-->

<p>
     For a <code>multiline=true</code> output text field, the system
     will compute a property <attribute>text.scrollHeight</attribute>
     which which you may examine. This field is not maintained for
     input text.
</p>


<p>There are two basic classes for displaying text,
<tagname>text</tagname> and <tagname>inputtext</tagname>.  The
<tagname link="true">text</tagname> class is used for displaying
text, while <tagname link="true">inputtext</tagname> is used
for input fields where the user can type or edit text interactively.
</p>
<h4>Resizable text fields</h4>
<p>
Take care when using text whose width must be calculated at run time.
Because the compiler does not know what the text
is (and the text field doesn't even know what it is until the contraints
evaluate),  it can't really know at construct time how wide to make itself.
</p>
<p>
If you add <code>resize=true</code>, the field will expand to fit the text. In the example below, notice how the last concatenation is invisible and the last digit of the numeric value from
the slider gets cut off. 
</p>
<example title="non-resizing text does not concatentate">
&lt;canvas&gt;
  &lt;simplelayout/&gt;
  &lt;slider name="down" width="100" value="5000" minvalue="1000" maxvalue="100000"
keystep="1000"/&gt;
  &lt;text text="${'Slider Value is '+parent.down.value+' nicely constrained'}"/&gt;
&lt;/canvas&gt;
</example>
<p>
The following shows the use of <attribute>resize="true"</attribute> to get the desired behavior.
</p>
<example title="Using the 'resize' attribute">

&lt;canvas&gt;
  &lt;simplelayout/&gt;
  &lt;slider name="down" width="100" value="5000" minvalue="1000" maxvalue="100000"
keystep="1000"/&gt;
  &lt;text <em>resize="true"</em> text="${'Slider Value is '+parent.down.value+' nicely constrained'}"/&gt;
&lt;/canvas&gt;
</example>

<h2><a name="textview">The <tagname>text</tagname> View</a></h2>
<p>
The <tagname link="true">text</tagname>  tag instantiates an <classname>LzText</classname> view. 
The text content can be specified at compile time using either of the two methods below; 
as the content of the <tagname>text</tagname> tag, or as the <attribute>text</attribute> attribute.
</p>

<example title="Text views">
&lt;canvas height="125"&gt;
  &lt;simplelayout/&gt;
  &lt;text&gt;Hello World!&lt;/text&gt;
  &lt;text text="Hello World!"/&gt;
&lt;/canvas&gt;
</example>

<h3><a name="multiline">Single-line and multiline text</a></h3>

<p>A text field can be either a single line or multiple lines. The <attribute>multiline</attribute> sets whether wrapping is enabled. The
default is a single-line text field. 
</p>

<example title="Multiline text">
&lt;canvas height="125">
  &lt;simplelayout spacing="5"/>
  &lt;!-- Single line text, the default -->
  &lt;text bgcolor="#ffcccc">
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras
    nibh. Quisque justo. Donec porta, wisi quis vehicula interdum,
    augue dui pharetra lectus, non adipiscing purus nibh vitae purus.
    &lt;/text>

    &lt;!-- Multiline text (without an explicit width, the width would be
     sized to fit the entire string on a single line) -->
    &lt;text bgcolor="#ccccff" multiline="true" width="300" >
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras
    nibh. Quisque justo. Donec porta, wisi quis vehicula interdum,
    augue dui pharetra lectus, non adipiscing purus nibh vitae purus.
  &lt;/text>
&lt;/canvas>
</example>


<p>With multiline text, the automatic wrapping is always enabled. You can disable wrapping
by setting the <attribute>multiline</attribute> to false. When multiline=false, the 
linebreaks will only be placed where you specify them in the text content, either as <code>&lt;br/&gt;</code> tags for HTML content, or newlines inside of a <code>&lt;pre/&gt;</code> preformatted text region. 
</p>


<example title="Multiline text with explicit linebreaks">
&lt;canvas height="125">
  &lt;simplelayout spacing="5"/>
  &lt;text bgcolor="#ccccff" multiline="true" width="400" >
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit.&lt;br/&gt; Cras
    nibh. Quisque justo. &lt;br/&gt;Donec porta, wisi quis vehicula interdum,
    augue dui pharetra lectus, non adipiscing purus nibh vitae purus.
  &lt;/text>
&lt;/canvas>
</example>

<p>Below is a non-wrapping text field with explicit line breaks.</p>
<example title="Non-wrapping text with breaks">
&lt;canvas height="125">
  &lt;simplelayout spacing="5"/>
  &lt;text bgcolor="#ccccff" multiline="false" width="500" height="100" >
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras&lt;br/&gt;
    nibh. Quisque justo. Donec porta, wisi quis vehicula interdum,&lt;br/&gt;
    augue dui pharetra lectus, non adipiscing purus nibh vitae purus.
  &lt;/text>
&lt;/canvas>
</example>



<!--=========================================================================-->
<!-- Comments are appreciated!                                                  -->
<!--=========================================================================-->
<h3><a name="width-height">Text Width and Height</a></h3>

<p>If no explicit text width and height attributes are supplied, the text field
will be sized to contain the initial text content. If the text view is single-line, 
then it will be sized to the height of the current font. 
</p>
<p>Setting the <attribute>resize</attribute> on a text field will cause it to be resized to
fit its text content at runtime, whenever the <method>setText()</method> method is called.
</p>

<p>
     Note: If no initial text content is specified, i.e., you have an
     empty tag such as  &lt;text/&gt; , then the text view will be sized to
     some nonzero default width and height. This helps in debugging
     applications, (especially in the case of text views which are
     initialized from datapaths) because zero width text fields
     would be invisible no matter what their text value was set to
     at runtime. 
        </p>

<example title="Resizing text">
&lt;canvas height="125"&gt;
  &lt;debug x="400"/&gt;
  &lt;simplelayout/&gt;
  &lt;!-- Single line text, the default --&gt;
  &lt;text id="t1" bgcolor="#ffcccc" resize="false"&gt;
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 
  &lt;/text&gt;
  &lt;text id="t2" bgcolor="#ccffcc" resize="true"&gt;
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  &lt;/text&gt;
  &lt;button text="setText(...)"&gt;
    &lt;method event="onclick"&gt;
      t1.setText('resize='+t1.resize);
      t2.setText('resize='+t2.resize);
    &lt;/method&gt;
  &lt;/button&gt;
&lt;/canvas&gt;
</example>

<h3><a name="selection">Text Selection</a></h3>

<p>Text can be made user-selectable with the <attribute>selectable</attribute> attribute.
This allows copy operations (and cut and paste, for inputtext) by the user. 
</p>

<example title="Selectable text">
&lt;canvas height="125"&gt;
  &lt;simplelayout spacing="4"/&gt;
  &lt;!-- Single line text, the default --&gt;
  &lt;text id="t1" bgcolor="#ffcccc" selectable="true" resize="false"&gt;
     I am selectable text. Select me!
  &lt;/text&gt;
  &lt;text id="t2" bgcolor="#ccffcc" resize="true"&gt;
    I am not selectable text. Try to select me!
  &lt;/text&gt;
&lt;/canvas&gt;
</example>

<h3>HTML Text Content</h3>

<p>Within a text view, a limited set of HTML tags and parameter
entities may be used to format the text.</p>

<table summary="HTML Tags">
<tr><th>Tag</th><th>Example</th></tr>
<tr><td><code>&lt;b&gt;</code></td><td><pre>&lt;b&gt;bold text&lt;/b&gt;</pre></td></tr>
<tr><td><code> &lt;a href="url"&gt;</code></td><td><pre>&lt;a href="http://www.boston.com"&gt;The Boston Globe&lt;/a&gt;</pre></td></tr>
<tr><td><code> &lt;font [color="#xxxxxx"] [face="Type Face"] [size="Type Size"]&gt;</code></td><td><pre>&lt;font color="#ff0000" face="myfont" size="12"&gt;Red text in LPS font 'myfont'&lt;/font&gt;</pre></td></tr>
<tr><td><code>&lt;i&gt;</code></td><td><pre>&lt;i&gt;italic text&lt;/i&gt;</pre></td></tr>
<tr><td><code> &lt;p&gt;</code></td><td><pre>line break &lt;p&gt; after p tag</pre></td></tr>
<tr><td><code>u</code></td><td><pre>&lt;u&gt;underline text&lt;/u&gt;</pre></td></tr>
<tr><td><code>&amp;quot;</code></td><td><pre>&quot;</pre></td></tr>
<tr><td><code>&amp;apos;</code></td><td><pre>&apos;</pre></td></tr>
<tr><td><code>&amp;amp;</code></td><td><pre>&amp;</pre></td></tr>
<tr><td><code>&amp;lt;</code></td><td><pre>&lt;</pre></td></tr>
<tr><td><code>&amp;gt;</code></td><td><pre>&gt;</pre></td></tr>
</table>
<p>
</p>

<example title="HTML tags in text views">
&lt;canvas height="125"&gt;
  &lt;font name="Times Roman"&gt;
    &lt;face src="timmonsr.ttf" /&gt;
    &lt;face src="timmonsb.ttf"  style="bold"/&gt;
    &lt;face src="timmonsi.ttf"  style="italic"/&gt;
    &lt;face src="timmonsbi.ttf" style="bold italic"/&gt;
  &lt;/font&gt;
  &lt;splash/&gt;
  &lt;view font="Times Roman" fontsize="16"&gt;
    &lt;simplelayout axis="y"/&gt;
    &lt;text&gt;
      normal &lt;i&gt;italic&lt;/i&gt; &lt;b&gt;bold&lt;/b&gt; &lt;b&gt;&lt;i&gt;bold-italic&lt;/i&gt;&lt;/b&gt;
      HTML Metachars: &amp;lt; &amp;gt; &amp;amp; &amp;quot;
    &lt;/text&gt;
    &lt;text&gt;
      &lt;font color="#FF0000"&gt;C&lt;/font&gt;&lt;font color="#FFFF00"&gt;O&lt;/font&gt;&lt;font color="#00FFCC"&gt;L&lt;/font
      &gt;&lt;font color="#CC00CC"&gt;O&lt;/font&gt;&lt;font color="#AABB00"&gt;R&lt;/font&gt;&lt;font color="#DDA00A"&gt;S&lt;/font&gt;
    &lt;/text&gt;
    &lt;text&gt;&lt;![CDATA[&lt;b&gt;this text shouldn't be bold, it's CDATA&lt;/b&gt;]]&gt;&lt;/text&gt; 
  &lt;text height="30"&gt;&lt;font size="24"&gt;This is a 24 point font.&lt;/font&gt;&lt;/text&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>


<!--note>
In flash6, the P tag can have an align=left|right|center option. 
</note-->



<h2>The <tagname>inputtext</tagname> View</h2>

<p>Editable text fields are created with the
<tagname>inputtext</tagname> tag. Like the non-editable
<tagname>text</tagname> view, an input text field can be single line
or multiline (wrapped).</p>

<h3>Handling Inputtext Selection</h3>

<p>
When a region of text is selected in an inputtext view, the  <method>getSelectionPosition</method> and <method>getSelectionSize</method> methods
can be used to obtain the offset and length of the selected text. The <method>setSelection</method>
selects a region of text in the view. 

</p>


<h3>Optimizing Input Text Performance</h3>
<p>

Due to some limitations of common older Flash Players, input text
fields in applications that are compiled to run on Flash 5 clients will have
slower performance if the text field does not have a fixed width and
height which can be determined by the compiler at compile time.
</p>
<p> The red inputtext field will have better performance  than
the blue one, which can be resized dynamically at runtime.
</p>

<example title="Optimizing inputt text performance ">
&lt;canvas height="200" width="900"&gt;
  &lt;window width="200" height="100" resizable="true"&gt;
    &lt;inputtext id="t1" width="201" height="100" resizable="false" multiline="true"
               bgcolor="#ffcccc"&gt;
      I have resizable=false, and have width and height computable at compile time.
      I will have optimized performance.&lt;/inputtext&gt;
  &lt;/window&gt;
  
  &lt;window width="200" height="100" x="250" resizable="true"&gt;
    &lt;inputtext id="t2" width="${parent.width}" height="${parent.height}"
               resizable="true" multiline="true" bgcolor="#ccccff"&gt;
      I am resizable, and my performance is not optimized&lt;/inputtext&gt;
  &lt;/window&gt;
&lt;/canvas&gt;
</example>

<p>
See <xref linkend="browser-integration"><a href="${dguide}browser-integration.html">Browser Integration</a></xref> for a discussion of browser-specific and Flash-specific
issues.</p>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
